Day 27｜Gateway API Key：額度與權限怎麼設計

昨天聊了 Web UI 跟用量追蹤。這個系統原本的驗證機制很簡單：一個 ROUTER_API_KEY 環境變數，管理介面跟對外的 Gateway 共用同一組 key 比對——這把 key 其實身兼兩種責任，「你是不是這個系統的操作者」跟「你能不能呼叫模型」，後來決定把這兩種責任拆給兩套獨立機制。今天要聊的，是拆出來之後，給外部呼叫端用的那一套：Gateway API Key。

Gateway API Key 是什麼

Gateway API Key 是給外部呼叫端（Cursor、自己寫的程式）用來認證身份、呼叫這個 Router 的憑證，跟存放在 Credential 裡、要打給廠商的那把 key 是完全不同的東西。這把 key 可以開多組，每一組各自帶額度上限、可以用哪些模型、到期日。驗證一把 key 時，依序做六層檢查——格式、查表、是否啟用、是否過期、額度夠不夠、模型權限——任何一層沒過就會被擋下來，但擋下來的理由會回傳不同的錯誤代碼，不是通通當成同一種「被拒絕」。

為什麼要做這個功能

Gateway API Key 這個功能其實一開始並不在計畫內。後來想到，這把 key 可以拿來控管不同專案各自的預算、限制能用哪些模型，而且也能防止真實廠商 key 外流的風險——外部拿到的只是這把可以被停用、額度有上限的 Gateway key，不是能直接打去廠商帳號的那把真實金鑰，才把這個功能加了回去。

兩把 key，兩種完全不同的儲存方式

Credential 的 key 跟 Gateway API Key 雖然都叫「key」，儲存方式卻完全不同。Credential 的 key 之後還要解密拿去打真正的廠商，所以用可逆的加密方式存；Gateway API Key 從頭到尾只需要拿使用者送過來的明文，雜湊之後跟資料庫存的雜湊值比對是否相符，不需要還原明文，所以直接用不可逆的雜湊方式存。同一個「key」，因為之後要不要被「拿回明文」用途不一樣，該用的保護方式也完全不同。

為什麼要分 429 跟 403 兩種拒絕

額度用完、跟模型權限不足，是兩種性質完全不同的拒絕：前者是「認得你，但這期的額度用完了」，換個週期或加值就能再用；後者是「認得你，但這把 key 天生就不能做這件事」，永久性的限制。把這兩者分成 429 跟 403 兩種不同的狀態碼，呼叫端就可以依照拿到的錯誤，判斷自己該不該重試、還是該換一把 key。

這也呼應到另一層防禦思維：這個系統預設會架在開發者自己的環境裡，就算 Gateway API Key 外流，外人也不容易連得進來——但即使多了這層環境上的保護，額度上限、模型權限這些機制還是不能省，因為防禦本來就該疊好幾層，不能只依賴其中一個環節不出問題。

三層備援的額度重置機制

額度重置做了三層：惰性重置，每次驗證這把 key 時順手檢查這期是否該重置，確保拿來用的當下額度一定是最新的；排程掃描，每隔一段時間掃一次所有設了重置日的 key，讓從沒被呼叫過的 key 在畫面上也能顯示正確的當期花費；手動重置按鈕，讓使用者想立刻重置時不用等到週期真的到。三種機制各自解決不同情境，不是重複的功能。

小結

拆掉 ROUTER_API_KEY 之後，Gateway API Key 承接了「誰能呼叫模型」這個責任，但它要處理的問題比原本那把單一金鑰複雜得多——怎麼存、怎麼分辨不同種類的拒絕、怎麼重置額度，每一個都是獨立的設計判斷。

明天要聊 MCP 能力查詢——為什麼讓它當 REST API 的 thin client，不直接碰資料庫。

專案開源與實作參考

如果大家看到這邊對這個專案有興趣，完整程式碼都已經整理並開源在 GitHub 上：

👉 GitHub Repo